﻿<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<link rel="Stylesheet" type="text/css" media="screen" href="Screen.css" />
  <title>StpCallback_EnableBpduTrapping</title>
</head>
<body>
	<h3>StpCallback_EnableBpduTrapping</h3>
	<hr />
<pre>
void StpCallback_EnableBpduTrapping
(
    const STP_BRIDGE* bridge,
    bool              enable,
    unsigned int      timestamp
);
</pre>
	<h4>
		Summary</h4>
	<p>
		Application-defined function that must 
		instruct the switching hardware to enable or disable trapping of BPDUs. This is 
		typically done by writing a few hardware registers of the switch IC.</p>
	<h4>
		Parameters</h4>
	<dl>
		<dt>bridge</dt>
		<dd>The application receives in this parameter a pointer to the bridge object returned by
			<a href="STP_CreateBridge.html">STP_CreateBridge</a>.</dd>
		<dt>enable</dt>
		<dd>The application receives in this parameter <code>true</code> if BPDU trapping is to be enabled,
			<code>false</code> if it is to be disabled.</dd>
		<dt>timestamp</dt>
		<dd>The same parameter that the application passed to <a href="STP_StartBridge.html">
			STP_StartBridge</a> or <a href="STP_StopBridge.html">STP_StopBridge</a> (these 
			are the only library functions that call this callback).</dd>
	</dl>
	<h4>
		Remarks</h4>
	<p>Most swich chips, after power up, treat BPDUs like regular multicast frames, 
		flooding them between ports. This is the desired behavior when STP is <em>not 
		enabled</em> on a switch. When STP <em>is enabled</em> on a switch, the desired behavior is to:</p>
	<ol>
		<li>trap all incoming BPDUs and forward them only to the management port (the
			port where the microcontroller running STP is wired), and also</li>
		<li>forward to a specific switch port those BPDUs generated by the STP library (the
			switch IC receives these on its management port).</li>
	</ol>
	<p><em>BPDUs</em> in this context means frames whose 
		destination address is 01:80:C2:00:00:00.</p>
	<p>The library calls this callback with <code>enable = true</code> from within the 
		<a href="STP_StartBridge.html">STP_StartBridge</a> function, and with <code>enable = 
		false</code> from within <a href="STP_StopBridge.html">STP_StopBridge</a>.</p>
	<p>When <code>enable</code> is <code>true</code>, the application callback should perform the following 
		operations on the switch:</p>
	<ul>
		<li>Configure the management port as single destination for incoming BPDUs (the management 
			port in this context means the port where the microcontroller running STP is 
			wired).</li>
		<li>Configure the switch IC to insert <em>source port information</em> (typically a 
			few bytes) into BPDUs received from the network, before forwarding them to the 
			management port. Later on, when the application that includes the STP library receives such a BPDU, it will need to parse this information before passing the BPDU payload 
			to <a href="STP_OnBpduReceived.html">STP_OnBpduReceived</a>.</li>
		<li>Configure the switch IC to decode and remove <em>destination port information</em> 
			from BPDUs received from the management port. (The STP library generates 
			these BPDUs and asks the application, via <a href="StpCallback_TransmitGetBuffer.html">
			StpCallback_TransmitGetBuffer</a> and
			<a href="StpCallback_TransmitReleaseBuffer.html">
			StpCallback_TransmitReleaseBuffer</a>, to send them to the switch IC, to be forwarded 
			by the switch IC to a specific port.)</li>
	</ul>
	<p>
		When <code>enable</code> is <code>false</code>, the application must undo all 
		these operations. This step must not be omitted; once STP is disabled on a switch, that 
		switch must resume flooding BPDUs between its ports, or else loops will form.</p>
	<p>
		Examples of implementations of this callback can be found in the embedded 
		applications provided with the library.</p>
	<p>
		<code>StpCallback_EnableBpduTrapping</code> is a placeholder name used throughout this documentation. The
		application may name this callback differently.</p>
	</body>
</html>
